From OpenTrials page: OpenTrials is a collaboration between Open Knowledge International and Dr Ben Goldacre from the University of Oxford DataLab. It aims to locate, match, and share all publicly accessible data and documents, on all trials conducted, on all medicines and other treatments, globally.
In addition to web search, the OpenTrials database is also accessible via API, documented as Open API (Swagger) format.
This short tutorial shows how to use this API from R with rapiclient.
Report rapiclient bugs on rapiclient issues. Source R Markdown for this page is here.
Report errors with OpenTrials data (for example, if a trial has incorrect treatments tagged to it) on this page.
Install rapiclient from Github:
devtools::install_github("bergant/rapiclient")
Use get_api and get_operations to create R client functions:
library(rapiclient)
open_trials_api <- get_api("http://api.opentrials.net/v1/swagger.yaml")
open_trials_schemas <- get_schemas(open_trials_api)
open_trials <- get_operations(open_trials_api, handle_response = content_or_stop)
names(open_trials)
## [1] "searchTrials" "autocomplete" "searchFDADocuments"
## [4] "getTrial" "getPublication" "getCondition"
## [7] "getOrganisation" "getRecords" "getRecord"
## [10] "getPerson" "getIntervention" "list"
## [13] "listFDAApplications" "getFDAApplication" "listDocuments"
## [16] "getDocument"
searchTrials returns trials based on a search query. By default, it’ll search in all of a trial’s attributes. Parameter q is a ElasticSearch query string. Parameters page (1 to 100) and per_page (10 to 100) are optional.
trials <- open_trials$searchTrials(q='public_title:(depressive OR depression)')
trials$total_count
## [1] 4050
length(trials$items)
## [1] 20
There are 4050 trials matching this search query and the first 20 already waiting in the trials$items list.
Take a look at the richness of the trial search result schema before using the results:
library(DiagrammeR)
grViz(
rapiclient::get_schema_graphviz_dot(
open_trials_api,
open_trials_api$definitions$TrialSearchResults
)
)
Print some of the trial attributes in a table:
library(dplyr)
library(knitr)
lapply(trials$items, function(x) { data.frame(
title = gsub("\n","",x$public_title),
source_id = x$source_id,
sample_size = ifelse(length(x$target_sample_size)==0, NA, x$target_sample_size),
status = x$status,
registered = format(as.POSIXct(x$registration_date)),
publications = length(x$publications),
stringsAsFactors = FALSE
)}) %>%
bind_rows %>%
arrange(desc(sample_size)) %>%
kable(caption = "Table: some data from trials search result")
| title | source_id | sample_size | status | registered | publications |
|---|---|---|---|---|---|
| Long-term Safety Study of Rapastinel as Adjunctive Therapy in Patients With Major Depressive Disorder | nct | 500 | ongoing | 2016-12-21 | 0 |
| Mental Health in Adults and Children- Frugal Innovations (MAC-FI): Adult Depression Component | nct | 256 | ongoing | 2016-12-20 | 0 |
| Reducing Fetal Exposure to Maternal Depression to Improve Infant Risk Mechanisms | nct | 240 | ongoing | 2017-01-04 | 0 |
| Conventional Bilateral rTMS vs. Bilateral Theta Burst Stimulation for Late-Life Depression | nct | 220 | ongoing | 2016-12-16 | 0 |
| Preeclampsia Research on Vitamin D, Inflammation, & Depression | nct | 200 | ongoing | 2016-12-08 | 0 |
| Study to Evaluate the Efficacy and Safety of Adjunctive Pimavanserin in Major Depressive Disorder (CLARITY) | nct | 188 | ongoing | 2017-01-10 | 0 |
| Stepped Care for Depression in Heart Failure | nct | 180 | ongoing | 2016-12-15 | 0 |
| Mantra Meditation in Major Depression | nct | 130 | ongoing | 2016-12-14 | 0 |
| Interpersonal Counseling (IPC) for Treatment of Depression in Adolescents | nct | 120 | ongoing | 2016-12-20 | 0 |
| Efficacy of H7-Coil DTMS Compared to H1-Coil DTMS in Subjects With Major Depression Disorder (MDD) | nct | 105 | ongoing | 2017-01-05 | 0 |
| Dynamics of Inflammation and Its Blockade on Motivational Circuitry in Depression | nct | 80 | ongoing | 2016-12-28 | 0 |
| Brief CBT for the Treatment of Depression During Inpatient Hospitalization | nct | 75 | ongoing | 2017-01-04 | 0 |
| A Study to Evaluate SAGE-217 in Subjects With Moderate to Severe Major Depressive Disorder | nct | 62 | ongoing | 2016-12-14 | 0 |
| Serum Cortisol Levels in Patients With Anxiety and Depression With Symptomatic Oral Lichen Planus | nct | 60 | ongoing | 2017-01-04 | 0 |
| Are Bright Lights and Regulated Sleep Effective Treatment for Depression? | nct | 60 | ongoing | 2017-01-03 | 0 |
| Effects of Online Cognitive Control Training on Rumination and Depressive Symptoms | nct | 52 | ongoing | 2016-12-19 | 0 |
| Emotional Awareness and SElf-regulation for Depression in Patients With Hypertension (EASE) Study | nct | 48 | ongoing | 2017-01-05 | 0 |
| CSE v. Epidural for Postpartum Depression | nct | 46 | ongoing | 2017-01-11 | 0 |
| Integrating HIV and Depression Self-Care to Improve Adherence in Perinatal Women | nct | 40 | ongoing | 2017-01-06 | 0 |
| The Experience of Older Adults Facing Depression for the First Time in Old Age | nct | 15 | ongoing | 2016-12-23 | 0 |
Print a function to see its documentation. For example:
open_trials$getTrial
## getTrial
##
## Description:
## Returns a trial's details and related entities (e.g. `conditions`).
##
## Parameters:
## id (string)
## ID of the trial
If parameter name is a reserved word in R, quote it with backticks:
conditions <-
open_trials$autocomplete(`in` = "condition", q = "depression depressive", per_page = 100) %>%
getElement("items") %>%
bind_rows %>%
select(id, name)
Note that operations are not vectorised. You have to use the *apply functions to get the data for arguments with length > 1. For example, count the trials for each condition:
conditions$trials <-
sapply(conditions$id, function(x) {
open_trials$searchTrials(q = sprintf("conditions.id:(%s)", x))[["total_count"]]
})
conditions %>% arrange(desc(trials)) %>% top_n(30, wt = trials) %>% knitr::kable(.)
| id | name | trials |
|---|---|---|
| 0188f4f0-10b1-44f2-b949-c95bee23b4e4 | F32.9 - Depressive episode, unspecified | 4 |
| 004267e9-a20b-49d2-8d73-4313ce59db78 | Topic: Mental Health Research Network, Primary Care Research Network for England; Subtopic: Depression, Not Assigned; Disease: Depression, All Diseases | 4 |
| 016ae19a-8c44-11e6-be70-0242ac12000f | Mental Depression | 2 |
| 01008ccb-c73d-4f15-8c10-2cb7ec1c65c9 | Late Life Depression (LLD) | 1 |
| 005a7e4e-b74d-4e96-a685-317923dab7c8 | Depression Anxiety Sleep disturbances Circadian disturbances | 1 |
| 00ae9a73-58f0-4871-b704-8399ffa79449 | Major depressive disorder (episode or recurrent), moderately severe as principal DSM-IV diagnosis | 1 |
| 00a154f8-8c6f-11e6-be70-0242ac12000f | Moderate to severe, or mild persistent, episode of Major Depression (DSM-IV) who initiate a new antidepressant treatment episode | 1 |
From Swagger definition (“http://api.opentrials.net/v1/swagger.yaml”)
searchTrials
Description: Returns trials based on a search query. By default, it’ll search in all of a trial’s attributes. - q is a ElasticSearch query string (e.g. public_title:(depressive OR depression)) - page can take a value between 1 and 100 - per_page can take a value between 10 and 100
autocomplete
Description: Autocomplete search feature for supported database entities (condition, intervention, location, person, organisation). It has the same options as a regular search operation, with an extra required in parameter indicating the entity type to search.
searchFDADocuments
Description: Search the FDA documents
getTrial
Description: Returns a trial’s details and related entities (e.g. conditions).
getPublication
Description: Returns publication details
getCondition
Description: Returns condition details
getOrganisation
Description: Returns organisation details
getRecords
Description: Returns a trial’s raw records from its sources
getRecord
Description: Returns a trial’s raw record from its sources
getPerson
Description: Returns person details
getIntervention
Description: Returns intervention details
list
Description: Returns list of sources
listFDAApplications
Description: Returns FDA applications
getFDAApplication
Description: Returns an FDA application details
listDocuments
Description: Returns documents
getDocument
Description: Returns details of a document
OpenTrials data sources:
sources <- open_trials$list()
knitr::kable(bind_rows(sources), caption = "Table of sources")
Xie Y (2016). knitr: A General-Purpose Package for Dynamic Report Generation in R. R package version 1.15.1, http://yihui.name/knitr/.
Wickham H and Francois R (2016). dplyr: A Grammar of Data Manipulation. R package version 0.5.0, https://CRAN.R-project.org/package=dplyr.
Sveidqvist K, Bostock M, Pettitt C, Daines M, Kashcha A and Iannone R (2017). DiagrammeR: Create Graph Diagrams and Flowcharts Using R. R package version 0.9.0, https://CRAN.R-project.org/package=DiagrammeR.
Other loaded packages in R session
Rcpp 0.12.9 http://www.rcpp.org, http://dirk.eddelbuettel.com/code/rcpp.html, https://github.com/RcppCore/Rcpp - highr 0.6 https://github.com/yihui/highr - RColorBrewer 1.1-2 - influenceR 0.1.0 https://github.com/rcc-uchicago/influenceR - plyr 1.8.4 http://had.co.nz/plyr, https://github.com/hadley/plyr - viridis 0.3.4 https://github.com/sjmgarnier/viridis - tools 3.3.2 - digest 0.6.11 http://dirk.eddelbuettel.com/code/digest.html - jsonlite 1.2 https://arxiv.org/abs/1403.2805, https://www.opencpu.org/posts/jsonlite-a-smarter-json-encoder - evaluate 0.10 https://github.com/hadley/evaluate - tibble 1.2 https://github.com/hadley/tibble - gtable 0.2.0 - rgexf 0.15.3 http://bitbucket.org/gvegayon/rgexf, http://www.ggvega.com - igraph 1.0.1 http://igraph.org - rstudioapi 0.6 - DBI 0.5-1 http://rstats-db.github.io/DBI - curl 2.3 https://github.com/jeroenooms/curl#readme - yaml 2.1.14 - gridExtra 2.2.1 https://github.com/baptiste/gridextra - httr 1.2.1 https://github.com/hadley/httr - stringr 1.1.0 https://github.com/hadley/stringr - htmlwidgets 0.8 https://github.com/ramnathv/htmlwidgets - rprojroot 1.1 https://github.com/krlmlr/rprojroot, https://krlmlr.github.io/rprojroot - grid 3.3.2 - R6 2.2.0 https://github.com/wch/R6/ - Rook 1.1-1 - XML 3.98-1.5 http://www.omegahat.net/RSXML - rmarkdown 1.3 http://rmarkdown.rstudio.com - ggplot2 2.2.1 http://ggplot2.tidyverse.org, https://github.com/tidyverse/ggplot2 - magrittr 1.5 - backports 1.0.4 https://github.com/mllg/backports - scales 0.4.1 https://github.com/hadley/scales - codetools 0.2-15 - htmltools 0.3.5 https://github.com/rstudio/htmltools - assertthat 0.1 - colorspace 1.3-2 https://hclwizard.org/ - brew 1.0-6 - stringi 1.1.2 http://www.gagolewski.com/software/stringi/ http://site.icu-project.org/ http://www.unicode.org/ - visNetwork 1.0.2 https://github.com/datastorm-open/visNetwork - lazyeval 0.2.0 - munsell 0.4.3